## Special debug functions

The `--debug-templates` flag enables advanced debugging mode for Go templates in werf.

In this mode:
-	Some errors become more detailed, including additional context that is hidden in normal mode.
-	Special functions for template debugging become available.
-	It is possible to output debug information to the log without affecting the result of the templating.

>️ Note: This verbose error behavior is enabled by default when `--debug-templates` is used, but it is not active in normal mode to avoid accidentally disclosing potentially sensitive data (such as secrets or internal values).

Below are scenarios where these functions can be useful and their behavior depending on the debug mode.

### Log an arbitrary message

You can insert custom log messages at any point during templating using `printf_debug`. This is useful for tracking variable values, condition execution, and the order of template rendering.

* **With `--debug-templates`**: the message is printed to the log and does not affect the rendering result;
* **Without `--debug-templates`**: the function does nothing.

Example:
{% raw %}
```bash
{{ printf_debug (printf "Current value: %v" .Values.someVar) }}
```
{% endraw %}

### Log a dump of any structure

If you need to inspect a variable's value — especially a complex one like `.Values` or `$` — use `dump_debug`.

* **With `--debug-templates`**: the structure is logged in a human-readable format and does not affect the rendering result;
* **Without `--debug-templates`**: the function does nothing.

Example:
{% raw %}
```bash
{{ dump_debug $.Values.werf }}
```
{% endraw %}

### Debug the `include` function

To debug `include` calls, replace them with `include_debug` and enable template debug mode using `--debug-templates`. This will log debug information about each `include` invocation during templating.

* **With `--debug-templates`**: works like `include`, but also logs the template name, its content, and the rendered result;
* **Without `--debug-templates`**: behaves like the standard `include`.

Example:
{% raw %}
```bash
{{ include_debug "my-template" . }}
```
{% endraw %}

### Debug the `tpl` function

To debug `tpl` calls, replace them with `tpl_debug` and enable template debug mode using `--debug-templates`. This will log debug information about each `tpl` invocation during templating.

* **With `--debug-templates`**: works like `tpl`, but also logs the template string and the rendered result;
* **Without `--debug-templates`**: behaves like the standard `tpl`.

Example:
{% raw %}
```bash
{{ tpl_debug "{{ .Values.env }}" . }}
```
{% endraw %}
